Add FTPS with SSL/TLS configuration by YasanPunch · Pull Request #1516 · ballerina-platform/module-ballerina-ftp

YasanPunch · 2025-12-08T09:25:06Z

Purpose

Fixes: ballerina-platform/ballerina-library/#8489

Adds FTPS (FTP over SSL/TLS) support to the FTP module, enabling secure file transfers using SSL/TLS certificates.

Changes:

Added FTPS protocol option to the Protocol enum
Added SecureSocket configuration type for FTPS SSL/TLS settings
Added FtpsMode enum to support IMPLICIT and EXPLICIT FTPS modes

public enum Protocol {
    FTP = "ftp",
    FTPS = "ftps",  // New: Secure File Transfer Protocol
    SFTP = "sftp"
}

# FTPS connection mode
public enum FtpsMode {
    IMPLICIT,   // SSL/TLS established immediately (port 990)
    EXPLICIT    // Upgrades to SSL/TLS via AUTH TLS (port 21)
}

# Secure socket configuration for FTPS
public type SecureSocket record {|
    crypto:KeyStore key?;
    crypto:TrustStore trustStore?;
    FtpsMode mode = EXPLICIT;
|};

public type AuthConfiguration record {|
    ...
    SecureSocket secureSocket?;  // New: For FTPS protocol
|};

(Current) Usage Example:

ftp:ClientConfiguration ftpsConfig = {
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21,
    auth: {
        credentials: {username: "user", password: "pass"},
        secureSocket: {
            key: {path: "client.p12", password: "keypass"},
            trustStore: {path: "truststore.p12", password: "trustpass"},
            mode: ftp:EXPLICIT
        }
    }
};

Future Enhancements (TODO):

Data channel protection level configuration (PROT P/C/S/E)
Hostname verification toggle for enhanced security
Test case development

Checklist

…nd SSL/TLS certificate handling.

CLAassistant · 2025-12-08T09:25:21Z

All committers have signed the CLA.

ballerina/commons.bal

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support in the current version of Apache Commons VFS2.

codecov · 2025-12-10T09:50:46Z

Codecov Report

❌ Patch coverage is 7.43982% with 423 lines in your changes missing coverage. Please review.
✅ Project coverage is 19.01%. Comparing base (dec8c19) to head (c9b7c36).

Files with missing lines	Patch %	Lines
.../ftp/transport/server/util/FileTransportUtils.java	7.89%	132 Missing and 8 partials ⚠️
...java/io/ballerina/stdlib/ftp/client/FtpClient.java	15.62%	97 Missing and 11 partials ⚠️
...ballerina/stdlib/ftp/server/FtpListenerHelper.java	0.00%	102 Missing ⚠️
...ain/java/io/ballerina/stdlib/ftp/util/FtpUtil.java	1.88%	51 Missing and 1 partial ⚠️
...ftp/transport/server/RemoteFileSystemConsumer.java	0.00%	20 Missing ⚠️
...connector/contractimpl/VfsClientConnectorImpl.java	50.00%	0 Missing and 1 partial ⚠️

❌ Your project status has failed because the head coverage (19.01%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@              Coverage Diff              @@
##             master    #1516       +/-   ##
=============================================
- Coverage     81.17%   19.01%   -62.17%     
+ Complexity      509      243      -266     
=============================================
  Files            40       55       +15     
  Lines          2561     3518      +957     
  Branches        407      622      +215     
=============================================
- Hits           2079      669     -1410     
- Misses          319     2746     +2427     
+ Partials        163      103       -60

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support.

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

… configuration - Introduced tests for FTPS client operations including explicit and implicit modes, file handling, and error scenarios. - Added tests for FTPS listener functionality, ensuring correct event handling for file changes. - Improved error handling for secure socket configurations in both client and server implementations. - Updated mock server utilities to include FTPS server initialization for testing purposes.

… relevant files for consistency, , remove hardcoded credentials and enhance password handling for improved security.

- Refactored test structure for better isolation and clarity. - Introduced helper functions for state management and event handling. - Improved file handling in tests, ensuring robust cleanup and setup. - Updated mock server utilities to ensure isolated test environments for FTPS operations.

…ments - Introduced a new configuration for testing the default port logic, ensuring that port 21 is correctly swapped to 990 for implicit mode. - Added a cleanup function to manage test environment state after execution. - Enhanced existing test cases to validate the new configuration and ensure robust error handling during FTPS operations.

- Updated the FTPS client test to use a more descriptive variable name for error handling. - Increased the wait count in listener tests to ensure proper event detection. - Improved error message clarity for invalid truststore scenarios in tests. - Adjusted the FtpClient to default to port 990 when port 21 is specified for implicit FTPS mode.

…ing age filtering and timeout handling.

sonarqubecloud · 2025-12-16T18:06:57Z

Quality Gate passed

Issues
17 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.5% Duplication on New Code

See analysis details on SonarQube Cloud

Yasan and others added 11 commits December 7, 2025 14:50

[Automated] Update the native jar versions

3c059a8

added SecureSocket record for FTPS

c0f3163

[Automated] Update the native jar versions

b7147a2

Added explicit/implicit modes

c7b5f7f

used ftpsconfigbuilder from apache vfs2

457e5af

Enhance FTPS support by adding explicit/implicit mode configuration a…

c9770d8

…nd SSL/TLS certificate handling.

[Automated] Update the native jar versions

7e66576

checkstyle fixes

fe853c0

[Automated] Update the native jar versions

2e458ce

[Automated] Update the native jar versions

300d366

updated sftp/ftps validation

e371bb8

YasanPunch requested review from DimuthuMadushan, MohamedSabthar, ThisaruGuruge and shafreenAnfar as code owners December 8, 2025 09:25

code improvement

c194857

niveathika reviewed Dec 8, 2025

View reviewed changes

ballerina/commons.bal Outdated Show resolved Hide resolved

YasanPunch added 9 commits December 9, 2025 12:37

Added data channel protection and host verification

09c055d

host verification fix

10776e0

fixed vfs config builder usage

7e7362c

fixed crypto:keystore integration issue

bdf7e34

Enhance FTPS configuration and KeyStore handling. Default port set to…

ac0a147

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

Updated methods to directly call configuration extraction functions, …

1622fce

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support in the current version of Apache Commons VFS2.

fixed checkstyle errors

2b0fffb

upated gradle properties

7222925

Updated gradle properties

d2940f0

YasanPunch added 2 commits December 11, 2025 11:20

code improvements

244925b

Remove FTPS hostname verification configuration from client and serve…

18687ba

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

YasanPunch and others added 28 commits December 16, 2025 22:13

fixed crypto:keystore integration issue

3903c6b

Enhance FTPS configuration and KeyStore handling. Default port set to…

6b9cb26

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

Updated methods to directly call configuration extraction functions, …

0ab1ef0

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support.

upated gradle properties

16c12ca

Remove FTPS hostname verification configuration from client and serve…

0f73cc0

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

[Automated] Update the native jar versions

bd1d401

initial test for ftps

670f53b

Refactor FTPS configuration: rename 'trustStore' to 'cert' across all…

1e47dc5

… relevant files for consistency, , remove hardcoded credentials and enhance password handling for improved security.

Implement onFileDeleted->onFileDelete method name change

702326f

Fix depreciation warning

5f1d525

Update spec

d126044

Update changelog

36d04e1

Fix grammer

138bb45

[Automated] Update the native jar versions

97cbb54

Upgrade task dependency

4b91caa

Add license headers

afdd8d8

Revert cron support temporality for relase

0d278a1

Remove FTPS secure publisher example files and resources

3668001

[Automated] Update the native jar versions

ab70b56

[Automated] Update the native jar versions

d757247

Add FTPS test cases for advanced configurations and validation includ…

37e9e6c

…ing age filtering and timeout handling.

[Automated] Update the native jar versions

7ba8f5a

Merge remote-tracking branch 'upstream/master' into add-ftps

95ef169

Merge branch 'add-ftps' into ftps-update

c9b7c36

YasanPunch closed this Dec 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add FTPS with SSL/TLS configuration#1516

Add FTPS with SSL/TLS configuration#1516
YasanPunch wants to merge 68 commits intoballerina-platform:masterfrom
YasanPunch:ftps-update

YasanPunch commented Dec 8, 2025 •

edited

Loading

Uh oh!

CLAassistant commented Dec 8, 2025 •

edited

Loading

Uh oh!

Uh oh!

codecov bot commented Dec 10, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

YasanPunch commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

Changes:

(Current) Usage Example:

Future Enhancements (TODO):

Checklist

Uh oh!

CLAassistant commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sonarqubecloud bot commented Dec 16, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

YasanPunch commented Dec 8, 2025 •

edited

Loading

CLAassistant commented Dec 8, 2025 •

edited

Loading

codecov bot commented Dec 10, 2025 •

edited

Loading